Skip to content

docs: describe the webhook signature as HMAC-SHA256 over the raw body (product update 2026-10-15) - #744

Open
hlenke wants to merge 1 commit into
mainfrom
docs-release/2026-10-28-webhook-signature
Open

hlenke wants to merge 1 commit into
mainfrom
docs-release/2026-10-28-webhook-signature

Conversation

@hlenke

@hlenke hlenke commented Oct 29, 2026 •

Copy link
Copy Markdown
Member

The webhooks page said payloads are signed with "the SHA256 hash algorithm" without saying what is signed, and the Node.js sample re-serialized the body before verifying it, which fails for text webhooks. This PR updates integrations/alerts/webhooks.mdx: the signature is an HMAC-SHA256 of the raw request body, the sample verifies the raw bytes, and a sentence explains that JSON templates stay valid JSON when a value contains quotes or line breaks.

Verified end to end against the released version.

Touches the same page as #481; merge order may matter.

🤖 Generated with Claude Code

… and verify raw bytes in the Node sample (monorepo #4904)

The alerting daemon signs each webhook with HMAC-SHA256 over the exact body
bytes it sends, hex-encoded in x-checkly-signature. The page called this a
"SHA256 hash" of the payload, and the Node.js sample re-serialised the parsed
body with JSON.stringify, which cannot verify plain text bodies and breaks
whenever the serialisation differs from the sent bytes. The sample now reads
the raw body with express.raw(). One sentence documents that JSON payload
templates stay valid JSON when an inserted value contains a double quote or a
line break, and how {{VAR}} and {{{VAR}}} render a double quote.

Proven on the local stack at monorepo 5858d7e03f: three webhook jobs built by
the alerting daemon, replayed byte for byte to a local receiver; 3/3 signatures
match HMAC-SHA256(secret, raw bytes); flipped byte, plain SHA256 and the old
text rule mismatch; old sample fails the text body, new sample passes all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
checkly-422f444a 🟢 Ready View Preview Oct 29, 2026, 1:50 AM

@hlenke hlenke changed the title docs: describe the webhook signature as HMAC-SHA256 over the raw body and verify raw bytes in the Node sample (monorepo #4904) docs: describe the webhook signature as HMAC-SHA256 over the raw body (product update 2026-10-15) Oct 29, 2026

This branch was successfully deployed

1 active deployment
staging — 03f76d88 Deployed Oct 29, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant